/** @mainpage AI Tester
*
* @author Tomas Hubik
*
* <br>
*
*
* @section intro Introduction
*
* This application provides a testing platform for artificial intelligence algorithms for turn based strathegic games.
* Besides this main feature, the %game implemented can be also played by human %players and supports also network games
* using AI Tester Server.
*
* <br>
* <hr>
* <br>
*
*
* @section requirements Requirements
*
* - Qt framework 4.4.0
* - qwt 5.2.0
* - AI Tester Server 0.9 for network games
*
* <br>
* <hr>
* <br>
* 
*
* @section architecture Architecture
*
* The application consists of these main components, that are representated as singletons:
*
* - game: Takses care of all %game logics, rules and comunicates with both players and network_client via messages and with game_gui via defined api
*
* - players: All %players ale stored here in array of player and singleton only takes care of this array
*
* - mapa: This singleton contains 2D array array2d terrain with representation of terrain in %game and array2d with objects in %game ( bonus and unit )
*
* - game_gui: This contains api funtions to handle whole %gui. It is implemented using Qt Widgets, but system architecture makes possible to
*             replace it by another, for example text %gui, that can be used on systems, where Qt Widgets are not supported. It is build of two parts.
*    -# game_gui::gui: contains Main window
*    -# game_gui::g_graphics: contains all QPixmap pixmaps, QSound sounds, QColor colors and ather stuff used in the %gui
*
* - network_client: All netwwork comminication with the server is managed by this client. It receives and decodes all messages and forwards them
*                   to game if needed. It is created only when playing over network.
*
*
* And these support components are representated also by singletons:
*
* - parameters: All %game %parameters loaded from file named <i>parameters.ait</i> are stored here. This singleton loads them and also provides access to them.
*               When it is loading %parameters, it also checks if the value is appropriate. Parameters are stored in 4 main cathegories:
*    -# parameters::game_parameters: Contains 4 default entries: MAX_PL (constraint to maximum %players, that can play the %game), MAX_UNITS (constraint to units
*                        number, that cane one %player own), START_TIME (time, that can one %player use in one turn), START_MONEY (money, that can one %player
*                        use to buy units)
*    -# parameters::gui_parameters: depends on %gui implementation, but here it contains only two %parameters: ICON_W and ICON_H, that is size of QPixmap used to represent
*                       one %map place. When you want to use bigger pixmaps, you have to change also this value
*    -# parameters::ai_parameters: this map is divided in subcathegories, where one subcathegory belongs to one algorithm and one subcathegory GENERAL, that is the same
*                      for all algorithms. In GENERAL subcathegory, there are a lot of coeficients, that are used to compute game_state score and one parameter
*                      ai_delay, that is used to watch simulation and is number of miliseconds between ai %players commands in play mode
*    -# parameters::network_parameters: there are currently no %parameters, bud it can be used for example for number of connect retries, some timeouts and so on
*    Adding a new parameter to %parameters is very easy. Adding entry to <i>parameters.ait</i> file if sufficient, and it can be accesset for example like that:
*    ai_parameters[ alg_name ][ param_name ], but when you want to add some checks for existance and value, the checks should be added by editting
*    parameters::check_parameters() and parameters::check_values() functions in parameters singleton.
*
* - prototypes: Here are stored prototypes of all %unit types and bonuses and they are used in buy mode. Unit %prototypes are loaded from <i>unit_types.ait</i> file and
*               adding of new %unit type is really easy and can be done only by adding line into this file. Adding of new %bonus type i a little bit more difficult
*               due to need of implementation of bonus::effect() function. So to add new %bonus type, you have to inherit from bonus class and implement
*               bonus::effect() function. Then the prototype have to be initialized in prototypes::prototypes( int _x ) constructor.
*
* - ai_algorithms: All %algorithm %prototypes are stored here. It is used for assigning an algorithm to the player. When implementating new %algorithm,
*                  it have to be added also into ai_algorithms::ai_algorithms( int _x ) constructor.
*
* <br>
*
*
* @subsection game Game
*
* The game singleton stores a lot of important information. At the beginning it sotres all objects loaded from file for future export. It also stores pointer
* to current %player ( game::current_player ), flag if %game is paused, or not, flag if it is network, or local, testing %game, %replay or normal. Beside this, it
* keeps current game_state for score displaying and passing it do ai %algorithms. During the %game it also stores history of scores to game::score_history
* and history of %players commands to game::players_commands also for future export of whole %replay. At the beginning of the %game, the %game starts buy mode. 
*
* At the beginning of the %game the game::start_buy() function is called. Then all functions are driven by messages from algorithms, %gui, that is controled by
* human and messages received from network_server. All these connections are made by Qt slots and signals. All messages are sent to
* game::command_received( player* pl, const string& command ) slot, so every single part of system, that is emitting messages have to be connected to this
* slot in order to deliver the messages to the %game core. There are 6 message types:
* - <b>BUY u x y</b>: This command is used for buying units in buy mode and has 3 %parameters: u is %unit id from prototypes singleton and x, y are coordinates,
*                     where the %unit should by placed ( [x;y] ). The id can be obtained by calling prototypes::units_name_pos( const string& nm ) function.
*                     Game core calls player::buy_unit( unit* u, unsigned int x, unsigned int y ) on current_player and if the %game is not %replay,
*                     it also saves command to the history. And if the %game is network %game, it sends command to other %players by
*                     network_client::deliver_command( player* pl, const string& cmd ).
* - <b>SEL u</b>: Command used for selling already bought units. Takes only one parameter, u, that is identification number of %unit, that should be sold.
*                 The number can be obtained by unit::get_id() function. Game core calls player::sell_unit( unsigned int u ) on current_player and if
*                 the %game is not %replay, it also saves command to the history. And if the %game is network %game, it sends command to other %players by
*                 network_client::deliver_command( player* pl, const string& cmd ).
* - <b>END</b>: This command is used for signalizing, that the sending %player finished buying units. game::end_buy() function is called and if
*               the %game is not %replay, it also saves command to the history. And if the %game is network %game, it sends command to other %players by
*               network_client::deliver_command( player* pl, const string& cmd ).
* - <b>MOV u x y</b>: Move events are encoded in this command, that has 3 %parameters: u is %unit id and x, y are coordinates, where the %unit should
*                     move ( [x;y] ). The id can be obtained by calling unit::get_id() function. Game core calls unit::move( unsigned int x, unsigned int y )
*                     on the %unit and if the %game is not %replay, it also saves command to the history. And if the %game is network %game, it sends command
*                     to other %players by network_client::deliver_command( player* pl, const string& cmd ).
* - <b>ATT u x y</b>: This is attacking command, that has 3 %parameters: u is %unit id and x, y are coordinates, where the %unit should
*                     attack ( [x;y] ). The id can be obtained by calling unit::get_id() function. Game core calls unit::fire( unsigned int x, unsigned int y )
*                     on the %unit and if the %game is not %replay, it also saves command to the history. And if the %game is network %game, it sends command
*                     to other %players by network_client::deliver_command( player* pl, const string& cmd ). It also checks, if the last enemy %unit was not
*                     destroyed and if the current_player won.
* - <b>NXT</b>: This command is used for signalizing, that the sending %player finished his turn. game::next_turn() function is called and if
*               the %game is not %replay, it also saves command to the history. And if the %game is network %game, it sends command to other %players by
*               network_client::deliver_command( player* pl, const string& cmd ).
*
* <br>
*
*
* @subsection game_gui Game GUI
*
* On application start, main_widget is set as central widget of the %gui. Each button, except About buttons and Exit one, will change the central widget.
*
* - <i>Local Game</i>: To local_setup_widget - here are the basic %parameters of the %game set, maps loaded and %game started via game::start_buy()
* - <i>Network Game</i>: To network_setup_widget - here are the basic %parameters of the %game set, network_client listener started and connected to the server
* - <i>Replay</i>: To replay_widget - this widget is for loading maps and commands needed for %replay and then %game is started via game::start_buy()
* - <i>Test Algorithms</i>: To testing_setup_widget - this is similar to local_setup_widget, but only ai %players can be added and %game will not show
*                                                     play_widget and buy_widget to show commands (%game progress can be analyzed after %game end using %replay mode)
* - <i>About Qt</i>: Shows About Qt window
* - <i>About</i>: Shows about AI Tester window
* - <i>Exit</i>: Exits the application
*
* At the %game end, game_end_widget if displayed using game_gui::show_game_end() function.
*
* <br>
*
*
* @subsection algorithms AI Algorithms
*
* Each %algorithm is inherited from abstract class algorithm, that provides basic interface. Example of the minimum, what to implement is stub_algorithm.
* Each algorithm have to implement constructor, that assignes value to algorithm::name, then it have to implement algorithm::clone() method, that is used
* to clone algorithm from prototypes and algorithm::register_me() method, that is used to register algorithm to prototypes. It is enough, to put right
* algorithm class name to templates in clone method and register_me() method. The most important methods are algorithm::get_buy_commands( game_state* gs ),
* that should generate commands to buy units ended with "END" command, that signalizes end of buy mode. Commands have to be put as strings to
* algorithm::commands list. Algorithm gets current state via parameter of the method. The parameter is not a clone of the state, so you must not delete it!!!
* Very similar and also as important as this is algorithm::get_commands( game_state* gs ), that is called by game at the beginning of each %players turn
* and should generate commands for play ended by "NXT" commands that singalizes end of turn.
*
* The game will take care of getting commands from algorithm::commands list by emitting signal algorithm::next_command().
*
* <br>
*
*
* @subsection network Network
*
* For all network communication takes care network_client singleton. It contains class Client, that is socket connected to the server. When some message
* arrives, Client::receive_message() slot is invoked and message will be processed. Messages has fixed structure. Message type, then '=' and then message content.
*
* There are only 7 of types of messages, that can be received:
*
* - <b>ACCEPTED</b>: contains one number, that is the number of %players, that receives the message assigned by the server
* - <b>SET_PLAYER</b>: contains network %players name in "", %players type and id. Processing this message sets new player to players. As reply, it
*                      sends "OK=3" message
* - <b>MAP</b>: contains terrain information. As reply, it sends "OK=0" message
* - <b>OBJECTS</b>: contains objects, that are on the map. As reply, it sends "OK=1" message
* - <b>START_BUY</b>: this message contains id of starting %player. Connects signals to game and runs game_gui::start_buy()
* - <b>ACTION</b>: this is message containing %game commands ( %player id ':' command )
* - <b>ERROR</b>: this type of message contains only error message, that is displayed via game_gui::show_network_error( const string& s )
*
* Here is a scheme of commands flow in the application and over network. AI Algorithm or Human produces command. Network_client will add client's id to
* the command and send it to the server.
*
* \image html server-client_messages.jpeg
*
*
*/